home *** CD-ROM | disk | FTP | other *** search
/ JCSM Shareware Collection 1996 September / JCSM Shareware Collection (JCS Distribution) (September 1996).ISO / fileutil / supdir11.zip / SDIR.DOC < prev    next >
Text File  |  1995-08-23  |  20KB  |  492 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.                                      SuperDIR (tm)
  21.                                Directory List Program.
  22.  
  23.                         Copyright 1995   Cottonwood Software.
  24.                                  All Rights Reserved
  25.  
  26.  
  27.                                     Users Manual
  28.                                     Version 1.11
  29.                                     23 Aug 1995
  30.                                  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.                                  _______
  42.                             ____|__     |                (R)
  43.                          --|       |    |-------------------
  44.                            |   ____|__  |  Association of
  45.                            |  |       |_|  Shareware
  46.                            |__|   o   |    Professionals
  47.                          -----|   |   |---------------------
  48.                               |___|___|    MEMBER
  49.  
  50.  
  51.                        'SuperDIR' Directory List Program
  52.  
  53.  
  54. About SuperDIR
  55. ---------------
  56.  
  57.   SuperDIR is a powerful directory lister with some unusual output options,
  58.   including:
  59.   - Comma-, Tab- and Space-delimited output options for import to databases
  60.   - Sorting files throughout directories (rather than just within the dir.)
  61.   - Multiple include and exclude filters for files and directory names
  62.   - Multiple paths/drives may be searched at once (registered version only)
  63.   - Indenting by directory level
  64.  
  65.   SuperDIR was designed for creating directory listings for import into 
  66.   spreadsheets or database programs.  The primary use is to make a 
  67.   complete file database of shareware CD-ROMs, for use by a shareware 
  68.   cataloging/extraction program.
  69.  
  70.   It is also useful in finding duplicate files on a disk, as well as being
  71.   a good general-purpose DIR replacement with multiple include/exclude
  72.   capabilities.
  73.  
  74.   The other intent was to 'showcase' some general C++ programming methods
  75.   such as objects, recursive objects, subclassing, encapsulation, etc.
  76.  
  77.   As a result of these objectives, there are no fancy graphical interfaces
  78.   in SuperDIR; just a hard-working program that spits out directory lines
  79.   one at a time.  
  80.   
  81.   You will get the complete source code when you register SuperDIR.
  82.  
  83.   The code is highly-modularized C++, which could be used in any number 
  84.   of projects that need directory information.  It also makes use of some 
  85.   general-purpose C++ class objects such as a command-line argument 
  86.   parser class and a linked-list class.  
  87.   
  88.   (See the section 'Registering' and ORDER.FRM for more information.)
  89.  
  90.   *************************************************************************
  91.   *** This program is shareware!  Feel free to use it and distribute it ***
  92.   *** wherever you like, as long as you distribute the program in its   ***
  93.   *** original and complete form.  (Vendors, see VENDOR.DOC.)           ***
  94.   ***                                                                   ***
  95.   *** If you like this program and intend to use it often, then please  ***
  96.   *** register (see below).  You will be notified of any updates and    ***
  97.   *** bug fixes automatically as a registred user.  And besides, it's   ***
  98.   *** the right thing to do!                                            ***
  99.   *************************************************************************
  100.  
  101.     Cottonwood Software is a member of the Association of Shareware
  102.     Professionals (ASP).  ASP wants to make sure that the shareware
  103.     principle works for you. If you are unable to resolve a
  104.     shareware-related problem with an ASP member by contacting the member
  105.     directly, ASP may be able to help. The ASP Ombudsman can help you
  106.     resolve a dispute or problem with an ASP member, but does not provide
  107.     technical support for members' products.  Please write to the ASP
  108.     Ombudsman at 545 Grover Road, Muskegon, MI USA 49442-9427, Fax
  109.     616-788-2765, or send a CompuServe message via CompuServe Mail to ASP
  110.     Ombudsman 70007,3536."
  111.  
  112.  
  113.  
  114. Packing List, Shareware Version
  115. -------------------------------
  116.  
  117.   You should have the following files:
  118.  
  119.     SDIR.EXE      The SuperDIR program
  120.     SDIR.DOC      This manual
  121.     README.1ST    Short introduction/instructions
  122.     ORDER.FRM     Registration/order form
  123.     FILE_ID.DIZ   Program description
  124.     VENDOR.DOC    Vendor information
  125.     REVISION.TXT  Revision history
  126.  
  127.   If any of these files are missing, please let your distributor know,
  128.   and contact the author to find out where to get a complete copy free
  129.   of charge.  (See 'Suggestions...' below)
  130.  
  131.  
  132. System Requirements
  133. -------------------
  134.  
  135.   To run SuperDIR, you need:
  136.     IBM PC/XT/AT compatible computer (8088 or higher processor)
  137.     MS-DOS 3.0 or higher (untested on lower versions)
  138.     At least 256K free RAM
  139.  
  140.   Windows Users:
  141.   --------------
  142.     SuperDIR may be run from a Windows DOS box (Command Prompt).  However,
  143.     this usually results in less memory available.  See the section
  144.     'Limitations' for more information.  A full Windows version is in the
  145.     works.  (Ask to be put on our mailing list for a free advance copy.)
  146.  
  147.  
  148.   This manual assumes general knowledge about PC's and the DOS operating
  149.   system.  There are many good books available that teach the basics of DOS
  150.   in your local bookstore or library.
  151.  
  152.  
  153. Installing and Running SuperDIR
  154. -------------------------------
  155.  
  156.   To install SuperDIR, copy the files to a suitable location on your hard
  157.   disk, creating a new directory if necessary.
  158.  
  159.   For example:
  160.     (This assumes that your current directory is where you now have SuperDIR)
  161.        MD C:\SDIR
  162.        COPY *.* C:\SDIR
  163.  
  164.   To run SuperDIR, simply type the program name (SDIR) at the DOS command
  165.   prompt.  Make sure you are in the directory containing the program, or
  166.   have the directory included in your PATH statement.  For more information,
  167.   refer to your MS-DOS or PC-DOS user's manual.
  168.  
  169.   To get a list of commands, type "SDIR /?" at the command prompt.
  170.  
  171.  
  172.  
  173.               *********** IMPORTANT WARRANTY INFORMATION **********
  174.  
  175.  
  176.                TRIAL USE (SHAREWARE EVALUATION VERSION) WARRANTY:
  177.                         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  178.                The Shareware evaluation (trial use) version is
  179.           provided AS IS. Cottonwood Software MAKES NO WARRANTY OF
  180.           ANY KIND, EXPRESSED OR IMPLIED, INCLUDING WITHOUT LIMITATION,
  181.           ANY WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
  182.           PARTICULAR PURPOSE.
  183.  
  184.  
  185.  
  186.                      REGISTERED VERSION LIFETIME WARRANTY:
  187.                        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  188.                Cottonwood Software warrants the physical diskette(s) and
  189.           physical documentation provided with registered versions to
  190.           be free of defects in materials and workmanship. If Cottonwood
  191.           Software receives notification of defects in materials or
  192.           workmanship, and such notification is determined by Cottonwood
  193.           Software to be correct, Cottonwood Software will replace the
  194.           defective diskette(s) or documentation.
  195.                The entire and exclusive liability and remedy for
  196.           breach of this Warranty shall be limited to replacement of
  197.           defective diskette(s) or documentation and shall not include
  198.           or extend to any claim for or right to recover any other
  199.           damages, including but not limited to, loss of profit, data,
  200.           or use of the software, or special, incidental, or consequential
  201.           damages or other similar claims, even if Cottonwood Software
  202.           has been specifically advised of the possibility of such damages.
  203.           In no event will Cottonwood Software's liability for any damages
  204.           to you or any other person ever exceed the lower of suggested
  205.           list price or actual price paid for the license to use the
  206.           software, regardless of any form of the claim.
  207.  
  208.                Cottonwood Software SPECIFICALLY DISCLAIMS ALL OTHER
  209.           WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  210.           TO, ANY IMPLIED WARRANTY OF MERCHANTABILITY AND/OR FITNESS
  211.           FOR A PARTICULAR PURPOSE.
  212.  
  213.               *********** IMPORTANT WARRANTY INFORMATION **********
  214.  
  215.  
  216.  
  217. Registering SuperDIR
  218. --------------------
  219.  
  220.   When you register this program, you not only get a version with all
  221.   'Unregistered' reminders removed, you get the complete source code which
  222.   will compile with Borland C++.  This code may be used freely for your own 
  223.   projects, or included in a non-competing product for resale, without any 
  224.   license or royalties required.  (We do ask that you notify us if it's 
  225.   used in a retail product, but we require no credits, license, or other 
  226.   reporting.)
  227.  
  228.   Benefits of registering:
  229.     Multiple-paths-at-once feature enabled (search all drives at once!)
  230.     The latest version as of the day you register, with no 'reminders'.
  231.     A printed manual.
  232.     A quick-reference card.
  233.     Full C++ source code for Borland C++ 3.1.
  234.     Free copy of another shareware program, CommEx. (Windows enhancement)
  235.     Notification of bug fixes and update releases when available.
  236.     Big discounts on updates and other products.
  237.     A good feeling that you're helping to support the shareware industry!
  238.  
  239.  
  240.   To register, send $17.00 (U.S.) plus $3.00 S&H ($5.00 S&H outside the U.S. 
  241.   or Canada) to:
  242.  
  243.       Cottonwood Software
  244.       P.O. Box 6546
  245.       Leawood, KS 66206-0546   USA
  246.  
  247.   Please pay by check in U.S. funds drawn on a U.S. Bank, by international
  248.   money order, or in U.S. currency.
  249.   (Do not send credit card orders to this address! See below for c.c. orders.)
  250.  
  251.   You may also register online through Compuserve: GO SWREG, product #5329.
  252.  
  253.   All orders are usually shipped within 24 hours.
  254.  
  255.  
  256.   CREDIT CARD ORDERS ONLY -
  257.  
  258.     You can order with MC, Visa, Amex, or Discover from Public (software)
  259.     Library by calling 800-2424-PsL or 713-524-6394 or by FAX to 713-524-6398
  260.     or by CIS Email to 71355,470. You can also mail credit card orders to PsL
  261.     at P.O.Box 35705, Houston, TX 77235-5705.
  262.  
  263.     Please refer to product ID #11950
  264.  
  265.     THE ABOVE NUMBERS ARE FOR CREDIT CARD ORDERS ONLY.
  266.     THE AUTHOR OF THIS PROGRAM CANNOT BE REACHED AT THESE NUMBERS.
  267.  
  268.     Any questions about the status of the shipment of the order, refunds,
  269.     registration options, product details, technical support, volume
  270.     discounts, dealer pricing, site licenses, non-credit card orders, etc,
  271.     must be directed to Cottonwood Software (see Suggestions... below).
  272.  
  273.     To insure that you get the latest version, PsL will notify us the day of
  274.     your order and we will ship the product directly to you the same or next
  275.     day.
  276.  
  277.  
  278. Suggestions, Comments, and Technical Support
  279. --------------------------------------------
  280.  
  281.   Any suggestions, comments, support questions and bug reports are welcome
  282.   and encouraged!  All questions will be answered promptly.  If you report
  283.   a bug, you will get a free updated copy in the mail (or however is most
  284.   convenient for us both) when the problem is fixed. This is offered to both
  285.   registered and unregistered users because we appreciate the assistance
  286.   in making the program better!
  287.  
  288.   The author may be reached at any of the following.  (E-mail is preferred)
  289.      Compuserve:       75264,1630
  290.      Internet:         75264.1630@compuserve.com
  291.      WWW Home Page:    http//delta.com/cotton/cotton.htm
  292.      Voice phone:      (913) 663-3022
  293.      FAX:              (913) 663-3747
  294.      Mail:             P.O. Box 6546   Leawood, KS  66206-0546  USA
  295.  
  296.  Support is offered at no charge for both registered and unregistered users,
  297.  for an unlimited time. (Unregistered users must use E-mail or call us so we 
  298.  don't incurr long-distance phone expenses.)
  299.  
  300.  If your version is not current, however, you will be asked to obtain the
  301.  newest version before any extensive support is given, so we know that any
  302.  problems you're having have not already been fixed.  We will tell you how
  303.  and where to get the latest shareware version, or we can send you the latest
  304.  version for a $3.00 handling fee ($5.00 outside the U.S.).
  305.  
  306.  
  307.  
  308.  
  309. Using SuperDIR -- Command Summary
  310. ---------------------------------
  311.  
  312.   Command format:
  313.  
  314.     SDIR [Path [Path]...] [switches]
  315.  
  316.     If no Path or switches are given, it works similar to DOS's DIR command.
  317.  
  318.     [Path] can include drive/directory and/or filename mask, like DOS's DIR.
  319.  
  320.     Multiple paths, even on different drives, may be specified if you're using
  321.     the registered version of SuperDIR. Up to 10 paths are allowed.  Only the
  322.     first path can have a file name or mask.
  323.  
  324.     Note: The /I switch will override (cancel) any file spec given in [path]
  325.  
  326.     To direct output to a file for use by other programs, use the DOS
  327.     redirection facility (>), like this:
  328.  
  329.       SDIR [Path] [switches] >filename
  330.  
  331.     It's a good idea to do it without redirection first to make sure it looks
  332.     the way you expect.  Also, avoid using the /P (pause) switch when
  333.     redirecting.
  334.  
  335.  
  336.   Switch summary:
  337.  
  338.     These can be either upper or lower case.
  339.     Some accept '-' prefix to turn off the switch, as noted below.
  340.  
  341.     /I   Include file filters (up to 10, sep. by semicolons, no spaces)
  342.            example:  /I*.c;*.h;sdir.*
  343.            Note:  This will override any file spec in [path]
  344.  
  345.     /X   Exclude file filters (up to 10, sep. by semicolons, no spaces)
  346.            example:  /X*.bak;*.obj;temp*.*
  347.  
  348.     /D   Include directory filters (up to 10, sep. by semicolons, no spaces)
  349.            example:  /Dwin*;word
  350.  
  351.     /E   Exclude directory filters (up to 10, sep. by semicolons, no spaces)
  352.            example:  /Etemp;tmp;dos;util;bat
  353.  
  354.     /S   Subdirectories (traverses all subdirectory levels)
  355.  
  356.     /.   (Default) Include . and .. subdirectories, or use /-. to turn off
  357.  
  358.     /P   Pause after 24 lines, or /Pnn to pause after nn lines
  359.  
  360.     /L   Output all lower-case (path and filename)  Upper case is default.
  361.  
  362.     /?   Displays help message
  363.  
  364.     /H   Displays help message
  365.  
  366.     /R   Displays Registration order form (use SDIR /R >lpt1: to print it)
  367.  
  368.  
  369. Using SuperDIR -- Command Summary (cont.)
  370. -----------------------------------------
  371.  
  372.     /A   Attribute inclusion -- must give list of attributes to include
  373.            example:  /Ahs
  374.  
  375.            Default is normal/archived files, plus subdirectories
  376.  
  377.            Valid attributes are:
  378.                h = hidden,      s = system,    r = read-only,
  379.                v = volume-ID,   a = archive,   d = subdirectories
  380.                n = do NOT show 'normal' files (eg. no attribs)
  381.  
  382.            Note that if /Ad is used (w/out others), ONLY subdirs are listed.
  383.  
  384.            Archive files and subdirs are normally listed, but use /Aa to
  385.            list the archive (& no-attrib) files WITHOUT the subdirectories.
  386.  
  387.  
  388.     /O   Sorting order specification; also must give sort elements/order.
  389.  
  390.          The order of the fields will determine the sorting priority.
  391.  
  392.              Elements are:
  393.                       n = name (without extension)
  394.                       e = extension
  395.                       s = size
  396.                       d = date/time (with seconds)
  397.                       a = attributes
  398.                       g = (default) group sorts by subdirectory
  399.                           (use g- to sort ALL files regardless of subdir.)
  400.                           (sorting is always separate for each Path given)
  401.  
  402.              Sort order is ascending by default, use '-' suffix to
  403.              specify descending order ('+' forces ascending order).
  404.  
  405.              Note: The same criteria will apply to the order of
  406.                    subdirectory traversal if the /S switch is used.
  407.  
  408.  
  409.     /F   Format specification; also must give format type:
  410.            /Ff = Fully-formatted output (Default, like DIR command output)
  411.            /Fq = Quote-delimited output (eg. "name.c","1234","12:34p")
  412.            /Ft = Tab-delimited output (eg. for word processor import)
  413.            /Fs = Space-delimited output (eg. for piping to other programs)
  414.  
  415.            Note:  /Fq, /Ft, and /Fs must be followed by a list of elements.
  416.               This list will also specify the order.  Elements are:
  417.                 p = path (ie. drive:\dir\sub ...)
  418.                 f = filename with extension
  419.                 n = name (without extension)
  420.                 e = extension
  421.                 s = size (in bytes)
  422.                 d = date
  423.                 t = time (in hh:mma format)
  424.                 m = military time, with seconds (hh:mm:ss)
  425.                 a = attributes (listed as lower-case letters, like "ahrs")
  426.                 x = full filename with path (eg c:\WINDOWS\WIN.INI)
  427.                 l = level of subdirectory (root = 1)
  428.  
  429.            example: /Fqpfs   (result: "dive:\path\","file.ext","size")
  430.  
  431.  
  432. Using SuperDIR -- Command Summary (cont.)
  433. -----------------------------------------
  434.  
  435.     These 3 switches are only valid for Fully-formatted (default) output:
  436.  
  437.     /T   Tab (indent) by subdirectory level (actually uses spaces, not tabs).
  438.     /B   (Default) Add breaks/path names between subdir's.  /-B to turn off
  439.     /Z   (Default) Print size and file totals at the end.   /-Z to turn off
  440.  
  441.  
  442. Limitations
  443. -----------
  444.  
  445.   The DOS command line limits the number of switches, filters, etc. that can
  446.   be used.  This problem will be addressed in the next release by allowing
  447.   a script file, environment settings, and perhaps an interactive input
  448.   option.  (Get on our mailing list to receive a free update!)  Note that you
  449.   can maximize switches by not putting spaces between them (a space is not
  450.   required between switches, only before the first switch).
  451.  
  452.   Because recursion is used for traversing directory trees, you may encounter
  453.   a stack overflow if you use the /S switch and have too many levels deep
  454.   in your directory structure.  This typically takes more than 20 levels to
  455.   be a problem.  You will probably reach DOS's 80-character path limit
  456.   before this!
  457.  
  458.   If you use a sorting command with the g- option (eg. /Ong-), you may
  459.   run out of memory.  This usually only happens with over 3000 files (such
  460.   as when doing "SDIR /Ong- /S" in the root directory of a large drive).
  461.   If this happens, try removing the g-, or do one subdirectory at a time.
  462.   You may also try excluding files or directories that aren't needed (/X
  463.   and /E), or free up more memory by removing some TSR's.  Future versions
  464.   will make use of Expanded/Extended memory.  (Registered users will get
  465.   this update free when it's available, scheduled for July 1995!)
  466.  
  467.   With minor changes, this program could be used to produce other formats,
  468.   such as space-delimited, DBF format, multi-column, etc.  These might be
  469.   included in future releases, but you can also add these features yourself
  470.   if you register and get the complete source code!
  471.  
  472.  
  473. Advanced uses
  474. -------------
  475.  
  476.   Because SDIR routes output to the standard output device, it's possible
  477.   to use its output as input to another program.  An example of this would
  478.   be using SDIR to list all *.BAK files on your hard disk, and routing
  479.   that list to a program that deletes them.  Use the space-delimited format
  480.   option (/Fs...) to output only the path and filename, and write a program 
  481.   that takes those and does a DEL on them.
  482.  
  483.   Other uses (some requiring simple auxiliary programs) include:
  484.     Printing out all FILE_ID.DIZ files and locations from a shareware CD.
  485.     Finding duplicate files (have SDIR sort so that they will be next to each
  486.       other so your programming part is easy), and printing a report of them.
  487.     Find all of the read-only or hidden files on a disk.
  488.     Find the total disk space used by certain file types (EXE, INI, etc.)
  489.  
  490.   Let me know if you come up with other interesting uses, or if a change
  491.   to SuperDIR would make your life easier!  Your input is appreciated!
  492.